home *** CD-ROM | disk | FTP | other *** search
/ Scene 96 / Scene 96 International Edition (Zyklop Software) (Disc 1) (1997).iso / emulator / amiga065 / docs / readme.pro < prev   
Text File  |  1996-12-20  |  8KB  |  140 lines
  1. You can help to make this program better. If you fix bugs or implement new
  2. features, I'd be grateful if you send me patches. For a list of interesting
  3. projects, and for a brief summary on how UAE works, see below.
  4.  
  5. A few guidelines for anyone who wants to help:
  6. - Please contact me first before you implement major new features. Someone 
  7.   else might be doing the same thing already. This has already happened :-(
  8.   Even if no one else is working on this feature, there might be alternative
  9.   and better/easier/more elegant ways to do it.
  10. - Some coding guidelines.
  11.   * Avoid GNU C extensions by all means. They make your code non-portable.
  12.   * Avoid GNU indentation style by all means. It makes your code unreadable.
  13.   * Try to indent your code nicely. There are editors like JED, which is
  14.     available from space.mit.edu:/pub/davis and highly recommendable, that do
  15.     this for you automatically.
  16.   * Use eight space tabs, four space tabs make a mess of the code.
  17. - If you have access to more than one Unix system, try compiling/running your
  18.   code on all of these. Remember, UAE is supposed to run on the DEC Alpha: so
  19.   don't assume sizeof(char*) == sizeof(int) == sizeof(long)
  20. - If you have more than one Kickstart, try your code with each one.
  21. - Patches are welcome in any form, but diff -u or diff -c output is preferred.
  22.   If I get whole source files, the first thing I do is to run diff on it. You 
  23.   can save me some work here (and make my mailbox smaller).
  24.  
  25. Some possible projects, in order of estimated difficulty:
  26. - Someone with a 68020 data sheet might check whether all opcodes are
  27.   decoded correctly and whether all instructions really do what they are 
  28.   supposed to do (I'm pretty sure it's OK by now, but you never know...).
  29. - Modify UAE to run in two threads for systems that have more than one CPU.
  30.   I've thought of a way how to do it, but I don't have a multiprocessor board
  31.   to try this. Here's how it works: Start with smart update method #1. This
  32.   method nicely bundles all the data necessary for drawing a scanline into two
  33.   structures: linedescr and line_data. Instead of actually drawing the line
  34.   in the main task, signal the second one to use that information. Synchronize
  35.   the two at the end of a frame to avoid lossage.
  36.   If I haven't overlooked a big problem, it should be trivial.
  37.   Sound output could also be moved into a separate task, but the gain will be
  38.   much smaller.
  39. - Improve the Kickstart replacement to boot more demos.
  40. - Snapshots as in CPE. Will need to collect all the variables containing
  41.   important information. Fairly easy, but boring. (Use core dumps instead :-)
  42. - Find out why uae.device has to be mounted manually with Kick 1.3.
  43.   The problem seems to be that we don't have a handler for it. I _think_ what
  44.   we need is the seglist of the standard filesystem handler. Problem is,
  45.   DOS hasn't been started when the devices are initialized and so we can't get
  46.   to the DosBase->RootNode->FileHandlerSeg pointer, and then there is the
  47.   confusing matter of BCPL GlobVecs and other weird stuff...
  48. - The playfield hardware is the only important part of the Amiga that is 
  49.   not really well documented in the HRM. Write some test programs that
  50.   do all sorts of weird things with the copper (like turning off bitplane 
  51.   DMA during a line, and turning it directly on again: VERY interesting
  52.   result) and try to emulate this perfectly.
  53.   Not _really_ necessary, I think: Surprisingly, and unlike 8 bit computer
  54.   software, Amiga programs usually seem to make use only of documented hardware
  55.   features.
  56. - Figure out a diskfile format that supports every possible non-standard
  57.   format.
  58. - Implement 68551 MMU. I have docs now. Not among the most necessary things.
  59. - Implement AGA support. Some bits and pieces exist.
  60. - Reimplement Amiga OS. (Well-behaved) Amiga programs could then be made
  61.   to use the X Window System as a "public screen". Of course, not all the
  62.   OS would have to be re-done, only Intuition/GFX. [Started, look at gfxlib.c]
  63. - Find some extremely clever ways to optimize the smart update methods. Maybe
  64.   try to support scrolling. Maybe find a way to update only parts of a line
  65.   (similar to LOW_BANDWIDTH). All such methods would probably be terribly
  66.   complicated, and not easy to get right without sacrificing compatibility.
  67.   Maybe it's not such a good idea.
  68. - Port it to Java and Emacs Lisp
  69. - A formal proof of correctness would be nice.
  70.  
  71. Things I don't really want to do:
  72. - Full ECS support, with braindamage like Productivity and SuperHires.
  73.  
  74.  
  75. How it works
  76.  
  77. Let's start with the memory emulation. All addressable memory is split into
  78. banks of 64K each. Each bank can define custom routines accessing bytes, 
  79. words, and longwords. All banks that really represent physical memory just 
  80. define these routines to write/read the specified amount of data to a chunk 
  81. of memory. This memory area is organized as an array of WORDs, which means 
  82. that those parts of the emulator that want to access memory in a linear 
  83. fashion can get a (WORD *) pointer and use it to circumvent the overhead of
  84. the put_word() and get_word() calls. That is done, for example, in the
  85. pfield_doline() function which handles screen refreshes.
  86. Memory banks that represent hardware registers (such as the custom chip bank
  87. at 0xDF0000) can trap reads/writes and take any necessary actions.
  88. In some places, this scheme is abused: The uae.device and unixfs.device are
  89. stored in a segment at 0xF00000 containing a ROMtag structure, so it is
  90. recognized at bootup. Since this is a ROM area, writes shouldn't occur
  91. normally and are therefore used to trap into emulation routines for these
  92. devices.
  93.  
  94. To provide a good emulation of graphical effects, only one thing is vital:
  95. Copper and playfield emulation have to be kept absolutely synchronous. If the
  96. copper writes to (say) a color register in a specific cycle, the playfield 
  97. hardware needs to use the new information in the next word of data it
  98. processes.
  99. UAE 0.1 used to call routines like do_pfield() and do_copper() each time the
  100. CPU emulator had finished an instruction. That was one of the reasons why it
  101. was so slow. Recent versions try to draw complete scanlines in one piece. This
  102. is possible if the copper does not write to any registers affecting the
  103. display during that scanline. Therefore, drawing the line is deferred until
  104. the last cycle of the line. If the copper writes to a hardware register before
  105. that, the function pfield_may_need_update() is called and this one determines
  106. whether it should fall back to the cycle-for-cycle approach. This is very
  107. rarely needed, mainly for copper-plasma effects and such, and the general case
  108. is much faster.
  109.  
  110. The CPU emulator no longer has to call all sorts of functions after each
  111. instruction. Instead, it keeps a list of events that are scheduled (timer
  112. interrupts, hsync and vsync events) and their "arrival time". Only the time
  113. for the next event is checked after each CPU instruction. If it's higher than
  114. the current cycle counter, the CPU can continue to execute.
  115.  
  116.  
  117. Portability
  118.  
  119. The main thing you need to worry about when porting UAE to a new platform is
  120. the OS dependent source file handling all the graphics output. Currently,
  121. there are xwin.c, svga.c, mac.c, dos-grx.c, dos-null.c, bebox.cpp and
  122. NeXTwin.m. Rewriting one of these to use the features of your operating
  123. system should be fairly easy.
  124. You might need to worry a little about datatypes. UAE requires that your C
  125. compiler supports 8 bit, 16 bit and 32 bit integers, otherwise a MC68000
  126. emulation would be not very easy to get right. Some typedefs to hide the
  127. actual types used can be found in amiga.h. The CPU emulation is not the only
  128. place that makes some potentially non-portable assumptions: The graphics
  129. code in custom.c, mainly the pfield_doline() function and its friends, may
  130. need some work if you have a really weird architecture.
  131. The only thing that's left are some Unixoid assumptions, mainly in
  132. filesys.c, but also in debug.c. Put in a few #ifdefs and modify the Makefile
  133. if necessary/possible, or make up a dummy unixfs-null.c file that contains 
  134. stubs.
  135. Apart from all that, it's fairly portable...
  136.  
  137.  
  138. How the compiler works
  139.  
  140.